﻿<?xml version="1.0" encoding="utf-8" ?> 

<patterns>

  <pattern>
    <class full-name="Patterns4Net.Core.Patterns.NullObject"/>
    <level>low</level>
    <description>
      <content>
        <summary>
          Null Object is an object with defined neutral ("<c>null</c>") behavior.
          In most object-oriented languages, such as Java or C#, references may be null.
          These references need to be checked to ensure they are not null before invoking any methods,
          because one can't invoke anything on a null reference.
        </summary>
        <remarks>
          <para>
            Here we present some example code:
            <code>
<![CDATA[
var null = new NullObject();
if (null.Operation()) {
	this.ActuallyNothingHappens();
}
]]>
            </code>
          </para>
          <para>
            Some other text that might be copied:Null Object is an object with
            defined neutral ("<c>null</c>") behavior.In most object-oriented languages, such as Java or C#,
            references may be null. These references need to be checked to ensure they
            are not null before invoking any methods,
            because one can't invoke anything on a null reference.
          </para>
          <para>
            <list>
              <listheader>
                <term>Advantages</term>
              </listheader>
              <item>
                <term>Avoid NullReference exception</term>
                <description>NullReference exceptions are really nasty...</description>
              </item>
              <item>
                <term>Shows your skills</term>
                <description>Only the advanced programmers know about design patterns...</description>
              </item>
            </list>
          </para>
        </remarks>
      </content>
      <sources>
        <source>http://en.wikipedia.org/wiki/Null_object</source>
      </sources>
    </description>
  </pattern>

  <pattern>
    <class full-name="Patterns4Net.Core.Patterns.Adapter"/>
    <level>low</level>
    <description>
      <content>
        <summary>
          Adapter translates one interface for a class into a compatible interface.
          An adapter allows classes to work together that normally could not because
          of incompatible interfaces, by providing its interface to clients while using
          the original interface. The adapter translates calls to its interface into calls
          to the original interface, and the amount of code necessary to do this is typically small.
          The adapter is also responsible for transforming data into appropriate forms.
          For instance, if multiple boolean values are stored as a single integer (i.e. flags) but your consumer
          requires a 'true'/'false', the adapter would be responsible for extracting
          the appropriate values from the integer value.
        </summary>
      </content>
      <sources>
        <source>http://en.wikipedia.org/wiki/Adapter_pattern</source>
      </sources>
    </description>
  </pattern>

  <pattern>
    <class full-name="Patterns4Net.Core.Patterns.Bridge"/>
    <level>normal</level>
    <description>
      <content>
        <summary>
          Bridge pattern is meant to "decouple an abstraction from its implementation so that the two can vary independently". 
          The bridge uses encapsulation, aggregation, and can use inheritance to separate responsibilities into different classes.
        </summary>
        <remarks>
          <para>
            When a class varies often, the features of object-oriented programming become very 
            useful because changes to a program's code can be made easily with minimal prior knowledge 
            about the program. The bridge pattern is useful when both the class as well as what it does vary often. 
            The class itself can be thought of as the implementation and what the class can do as the abstraction. 
            The bridge pattern can also be thought of as two layers of abstraction.
          </para>
        </remarks>
      </content>
      <sources>
        <source>http://en.wikipedia.org/wiki/Bridge_pattern</source>
      </sources>
    </description>
  </pattern>

  <pattern>
    <class full-name="Patterns4Net.Core.Patterns.Composite"/>
    <level>low</level>
    <description>
      <content>
        <summary>
          Composite pattern is a partitioning design pattern. 
          The composite pattern describes that a group of objects are to be treated in 
          the same way as a single instance of an object. The intent of a composite is 
          to "compose" objects into tree structures to represent part-whole hierarchies. 
          Implementing the composite pattern lets clients treat individual objects and compositions uniformly.
        </summary>
        <remarks>
          <para>
            When dealing with tree-structured data, programmers often have to discriminate between a leaf-node and a branch. 
            This makes code more complex, and therefore, error prone. The solution is an interface that allows treating 
            complex and primitive objects uniformly. A composite is an object 
            designed as a composition of one-or-more similar objects, all exhibiting similar functionality. 
            This is known as a "has-a" relationship between objects. The key concept is that you can manipulate a 
            single instance of the object just as you would manipulate a group of them. 
            The operations you can perform on all the composite objects often have a least common denominator relationship. 
            For example, if defining a system to portray grouped shapes on a screen, it would be useful to 
            define resizing a group of shapes to have the same effect (in some sense) as resizing a single shape.
          </para>
        </remarks>
      </content>
      <sources>
        <source>http://en.wikipedia.org/wiki/Composite_pattern</source>
      </sources>
    </description>
  </pattern>

  <pattern>
    <class full-name="Patterns4Net.Core.Patterns.Decorator"/>
    <level>low</level>
    <description>
      <content>
        <summary>
          The decorator pattern can be used to make it possible to extend (decorate) the functionality of a 
          certain object at runtime, independently of other instances of the same class, provided some 
          groundwork is done at design time. This is achieved by designing a new 
          decorator class that wraps the original class.
        </summary>
        <remarks>
          <para>
            This pattern is designed so that multiple decorators can be stacked on top of each other, 
            each time adding a new functionality to the overridden method(s).
          </para>
          <para>
            The decorator pattern is an alternative to subclassing. Subclassing adds behavior at compile time, 
            and the change affects all instances of the original class; decorating can provide new behavior 
            at runtime for individual objects.
          </para>
          <para>
            This difference becomes most important when there are several independent ways of extending functionality. 
            In some object-oriented programming languages, classes cannot be created at runtime, and it is typically 
            not possible to predict, at design time, what combinations of extensions will be needed. 
            This would mean that a new class would have to be made for every possible combination. 
            By contrast, decorators are objects, created at runtime, and can be combined on a per-use basis. 
            The I/O Streams implementations of both Java and the .NET Framework incorporate the decorator pattern.
          </para>
        </remarks>
      </content>
      <sources>
        <source>http://en.wikipedia.org/wiki/Decorator_pattern</source>
      </sources>
    </description>
  </pattern>

  <pattern>
    <class full-name="Patterns4Net.Core.Patterns.FactoryMethod"/>
    <level>normal</level>
    <description>
      <content>
        <summary>
          The factory method pattern is an object-oriented design pattern to implement the concept of factories. 
          Like other creational patterns, it deals with the problem of creating objects (products) without 
          specifying the exact class of object that will be created. The creation of an object often 
          requires complex processes not appropriate to include within a composing object. 
          The object's creation may lead to a significant duplication of code, may require information not 
          accessible to the composing object, may not provide a sufficient level of abstraction, 
          or may otherwise not be part of the composing object's concerns. 
          The factory method design pattern handles these problems by defining a separate method for creating the objects, 
          which subclasses can then override to specify the derived type of product that will be created.
        </summary>
        <remarks>
          <para>
            A factory object typically has a method for every kind of object it is capable of creating.
            These methods optionally accept parameters defining how the object is created, and then return the created object.
          </para>
          <para>
            Factory objects are used in situations where getting hold of an object of a particular kind is a more 
            complex process than simply creating a new object. The factory object might decide to create the 
            object's class (if applicable) dynamically, return it from an object pool, do complex configuration 
            on the object, or other things.
          </para>
        </remarks>
      </content>
      <sources>
        <source>http://en.wikipedia.org/wiki/Factory_method_pattern</source>
      </sources>
    </description>
  </pattern>

  <pattern>
    <class full-name="Patterns4Net.Core.Patterns.Immutable"/>
    <description>
      <content>
        <summary>
          In object-oriented and functional programming, an immutable object is an object whose state cannot be 
          modified after it is created. This is in contrast to a mutable object, which can be modified after it is created.
        </summary>
        <remarks>
          <para>
            Immutability does not imply that the object as stored in the computer's memory is unwriteable. 
            Rather, immutability is a compile-time construct that indicates what a programmer can do through the 
            normal interface of the object, not necessarily what they can absolutely do 
            (for instance, by using the Reflection in .NET).
          </para>
          <para>
            Patterns4Net requires immutable objects to forbid changes of the internal state from outside
            (through public interface, even transitively) once the object is returned to the 'outside world'. 
            The following example shows an immutable object with factory method that changes the state of 
            it's product, which is valid, because the product is local variable and has not been returned yet. 
            <code>
<![CDATA[
class ImmutableObject {
  private int i;  
  public static ImmutableObject Create(int i) {
    var result = new ImmutableObject();
    result.i = i;
    return result;
  }
}
]]>
            </code>
          </para>
        </remarks>
      </content>
      <sources>
        <source>http://en.wikipedia.org/wiki/Immutable</source>
      </sources>
    </description>
  </pattern>

  <pattern>
    <class full-name="Patterns4Net.Core.Patterns.Prototype"/>
    <description>
      <content>
        <summary>
          The prototype pattern is a creational design pattern used in software development when the type of objects 
          to create is determined by a prototypical instance, which is cloned to produce new objects. This pattern is used to:
          avoid subclasses of an object creator in the client application, like the abstract factory pattern does; and/or 
          avoid the inherent cost of creating a new object in the standard way (e.g., using the 'new' keyword) 
          when it is prohibitively expensive for a given application.
        </summary>
        <remarks>
          <para>
            In .NET prototype is typically implemented by implementing the <c>ICloneable</c> interface. 
            Implementation of this interface is enforced by Pattern Enforcer.
          </para>
        </remarks>
      </content>
      <sources>
        <source>http://en.wikipedia.org/wiki/Prototype_pattern</source>
      </sources>
    </description>
  </pattern>

  <pattern>
    <class full-name="Patterns4Net.Core.Patterns.Proxy"/>
    <level>low</level>
    <description>
      <content>
        <summary>
          A proxy, in its most general form, is a class functioning as an interface to something else. 
          The proxy could interface to anything: a network connection, a large object in memory, a file, 
          or some other resource that is expensive or impossible to duplicate.    
        </summary>
        <remarks>
          <para>
            In situations where multiple copies of a complex object must exist the proxy pattern can be adapted 
            to incorporate the flyweight pattern in order to reduce the application's memory footprint. 
            Typically one instance of the complex object is created, and multiple proxy objects are created, 
            all of which contain a reference to the single original complex object. 
            Any operations performed on the proxies are forwarded to the original object. 
            Once all instances of the proxy are out of scope, the complex object's memory may be deallocated.
          </para>
          <para>A well-known example of the proxy pattern is a reference counting pointer object.</para>
        </remarks>
      </content>
      <sources>
        <source>http://en.wikipedia.org/wiki/Proxy_pattern</source>
      </sources>
    </description>
  </pattern>

  <pattern>
    <class full-name="Patterns4Net.Core.Patterns.SimpleFactoryMethod"/>
    <level>low</level>
    <description>
      <content>
        <summary>
          Simple Factory Method is a static method that serves to encapsulate the 
          creation of an object. However, since it is static method, it does not 
          provide such flexibility as Factory Method or Abstract Factory.
        </summary>
      </content>
      <sources>
        <source></source>
      </sources>
    </description>
  </pattern>

  <pattern>
    <class full-name="Patterns4Net.Core.Patterns.Singleton"/>
    <level>higher</level>
    <description>
      <content>
        <summary>
          The singleton pattern is a design pattern used to implement the mathematical concept of a singleton, 
          by restricting the instantiation of a class to one object. This is useful when exactly one object is 
          needed to coordinate actions across the system. The concept is sometimes generalized to systems that 
          operate more efficiently when only one object exists, or that restrict the instantiation to a certain 
          number of objects (say, five). 
        </summary>
        <remarks>
          <para>
            Some consider it an anti-pattern, judging that it is overused, introduces unnecessary limitations in situations 
            where a sole instance of a class is not actually required, and introduces global state into an application.
          </para>
          <para>
            Pattern Enforcer supports three implementations of the Singleton pattern.
            <list type="table">
              <item>
                <term>Static member</term>
                <description>
                  The singleton instance is initialized in static constructor of the class in question.
                </description>
              </item>
              <item>
                <term>Nested class</term>
                <description>
                  The singleton instance is initialized in static constructor of a 
                  class nested in the class in question. This provides better lazines 
                  than previous approach.
                </description>
              </item>
              <item>                
                <term>Static factory</term>
                <description>
                  The singleton object is lazily created in a static factory method 
                  using the following code pattern:
                </description>
              </item>
            </list>
            <code>
<![CDATA[
// ...
if (instance == null) {
  instance = new MySingleton();
}
// ...
return instance;
]]>              
            </code>
          </para>
        </remarks>
      </content>
      <sources>
        <source>http://en.wikipedia.org/wiki/Singleton_pattern</source>
      </sources>
    </description>
  </pattern>

  <pattern>
    <class full-name="Patterns4Net.Core.Patterns.Strategy"/>
    <level>normal</level>
    <description>
      <content>
        <summary>
            Strategy pattern defines a family of algorithms, encapsulates each one, and makes them interchangeable. 
            The Strategy pattern lets the algorithm vary independently from clients that use it.
        </summary>
        <remarks>
          <para>
            The strategy pattern is intended to provide a means to define a family of algorithms,
            encapsulate each one as an object, and make them interchangeable.
          </para>
          <para>
            For instance, a class that performs validation on incoming data may use a strategy pattern to select a
            validation algorithm based on the type of data, the source of the data, or other discriminating factors.
            These factors are not known for each case until run-time, and may require radically different validation
            to be performed. The validation strategies, encapsulated separately from the validating object, may be
            used by other validating objects in different areas of the system (or even different systems) without code duplication.
          </para>
          <para>
            The essential requirement in the programming language is the ability to store a reference to some code in 
            a data structure and retrieve it. This can be achieved by mechanisms such as the native function pointer, 
            the first-class function, classes or class instances in object-oriented programming languages, or 
            accessing the language implementation's internal storage of code via reflection.
          </para>
          <para>
            Pattern Enforcer requires a strategy interface or an abstract base class to define just one operation, 
            which is the ecapsulated algorithm.
          </para>
        </remarks>
      </content>
      <sources>
        <source>http://en.wikipedia.org/wiki/Strategy_design_pattern</source>
      </sources>
    </description>
  </pattern>

  <pattern>
    <class full-name="Patterns4Net.Core.Patterns.TemplateMethod"/>
    <level>low</level>
    <description>
      <content>
        <summary>
          A template method defines the program skeleton of an algorithm. One or more of the algorithm steps 
          can be overridden by subclasses to allow differing behaviors while ensuring that the 
          overarching algorithm is still followed.
        </summary>
        <remarks>
          <para>
            In object-oriented programming, first a class is created that provides the basic steps of an algorithm design. 
            These steps are implemented using abstract methods. Later on, subclasses change the abstract methods to 
            implement real actions. Thus the general algorithm is saved in one place but the concrete steps 
            may be changed by the subclasses.
          </para>
          <para>
            The template method thus manages the larger picture of task semantics, and more refined implementation 
            details of selection and sequence of methods. This larger picture calls abstract and non-abstract methods 
            for the task at hand. The non-abstract methods are completely controlled by the template method but 
            the abstract methods, implemented in subclasses, provide the pattern's expressive power and degree of freedom. 
            Some or all of the abstract methods can be specialized in a subclass, allowing the writer of the subclass 
            to provide particular behavior with minimal modifications to the larger semantics. 
            The template method (which is non-abstract) remains unchanged in this pattern, 
            ensuring that the subordinate non-abstract methods and abstract methods are called in the originally-intended sequence.
          </para>
          <para>
            Pattern Enforcer enforces that a template method ivokes at least one virtual method.
          </para>
        </remarks>
      </content>
      <sources>
        <source></source>
      </sources>
    </description>
  </pattern>

  <pattern>
    <class full-name="Patterns4Net.Core.Patterns."/>
    <level>normal</level>
    <description>
      <content>
        <summary>
          The visitor design pattern is a way of separating an algorithm from an object structure it operates on. 
          A practical result of this separation is the ability to add new operations to existing object structures 
          without modifying those structures. It is one way to easily follow the open/closed principle.
        </summary>
        <remarks>
          <para>
            In essence, the visitor allows one to add new virtual functions to a family of 
            classes without modifying the classes themselves; instead, one creates a visitor 
            class that implements all of the appropriate specializations of the virtual function. 
            The visitor takes the instance reference as input, and implements the goal through double dispatch.
          </para>
          <para>
            In .NET the visitor pattern can be implemented using Reflection to emulate double dispatch, 
            using dynamic keyword, which provides double dispatch, or by simulating double dispatch by 
            a special method on each element of the structure as described in more detail in 
            Design Patterns book.
          </para>
          <para>
            Pattern Enforcer only enforces correctness of the last implementation. 
            However, the other two implementations are possible, but not verified 
            by Pattern Enforcer.
          </para>
        </remarks>
      </content>
      <sources>
        <source>http://en.wikipedia.org/wiki/Visitor_pattern</source>
      </sources>
    </description>
  </pattern>

  <pattern>
    <class full-name="Patterns4Net.Attributes.DesignPatterns.StateAttribute"/>
    <level>low</level>
    <description>
      <content>
        <summary>
          The state pattern is a behavioral software design pattern, 
          also known as the objects for states pattern. 
          This pattern is used to represent the state of an object. 
          This is a clean way for an object to partially change its type at runtime.
        </summary>
      </content>
      <sources>
        <source>http://en.wikipedia.org/wiki/State_pattern</source>
      </sources>
    </description>
  </pattern>

  <!-- Template: 
  <pattern>
    <class full-name="Patterns4Net.Core.Patterns."/>
    <level></level>
    <description>
      <content>
        <summary>
          
        </summary>
      </content>
      <sources>
        <source></source>
      </sources>
    </description>
  </pattern>
  -->
  
</patterns>
